This documentation and the software it describes are
Copyright (C) 1985 by Scott Ballantyne
Distribution on a not for profit basis is encouraged.
Sale or Resale of this manual or software is not allowed.*cn0
*fp0
*ln5
I would like to acknowledge the following people, who contributed time, support or knowledge to this effort:
Glen Haydon, author of MVP-FORTH, whose book ALL ABOUT FORTH was my constant companion during the early stages of this project.
Henry Laxen, Forth Wizard and writer. Many of the best features of this compiler are due to his ideas, and his columns in Forth Dimensions are among the best and most creative writing on Forth I have ever seen. In particular, Laxen is the creator of the DEFER IS concept.
To RMS and WRG, wherever you are, thanks for everything you taught me.
Thanks to Chris M. A friend indeed.
Special thanks to BJ, who knows what she did.
Thanks to all those who put up with various versions of this compiler, and suffered almost as much as I did while debugging it.
CBM C64 C128 and Commodore-64 are trademarks of Commodore Business Machines.
*ln6
This software is dedicated to the memory of Leonard Rose.
*fp0
*cn1;Introduction*cn0
This manual describes the special features of the Blazin' Forth compiler. It is not necessary to read the entire document before using the compiler.
I would strongly urge you to at least glance through the first part paying special attention to the sections describing MOUNT and the EDITOR.
Once this has been taken care of, you may proceed immediately to the portion you are most interested in. Blazin' Forth supports the sound chip, Turtle Graphics, and Sprites, as well as containing a complete string handling package. Please feel free to start with the sections which interest you the most.
Blazin' Forth is a complete Forth-83 system for the Commodore-64 computer. It includes all the words from the Required Word Set, the Double Number Extension Word Set, and the Assembler Extension Word set. It also includes almost all of the Controlled Reference Word set, and applicable words from the Uncontrolled Reference Word Set. The words omitted from the Controlled Word Set are --> , K , and Octal , all others are included. This system also contains its own versions of the System Extension Word Set, which include various compiler security features.
In short, this is a complete implementation of the Forth-83 standard, suitable for developing programs which may be ported to other systems, or running programs developed on other systems.
There are also various extensions to the standard system, which include additional boolean operators, words like ?KEY , ?DO, and ?LEAVE , which are very useful, but not yet part of the standard Forth language.
When I first started writing this compiler, I had two main goals in mind. The first was to have a fast Forth-83 compiler on the C64. The other was to provide access to all of the nifty hardware features of this computer. Blazin' Forth includes words which make it simple to access the sound chip, and graphics chips of the 64. In particular, it includes a Turtle Graphics extension, which is by far the fastest implementation on the C64 I have ever seen.
This document describes all of the features specific to Blazin' Forth. For information on Forth, I would suggest you obtain a copy of the Forth-83 standard, which is available from the Forth Interest Group (FIG) for a few dollars. If you are new to Forth, the book Starting Forth, by Leo Brodie, contains a very complete tutorial on the Forth Language. There is a file available, Start Blazin' Forth, which is intended to help you over the hurdles caused by the differences between the Starting Forth dialect of Forth (which is an earlier implementation of Forth) and Forth-83. Note that there are not many differences between the two.
This system, its documentation and source code are Copyright (C) 1985 by Scott Ballantyne. Free distribution of this compiler is encouraged, distribution for profit is not allowed. (Users Groups and SYSOP's of bulletin boards may charge a small fee to cover their operating expenses. If in doubt, please ask.) Note that this system is not public domain, nor is it freeware. I don't want your money. If you like this system, why not contribute some software of your own? On the other hand, if you don't like it, why don't you contribute some software of your own? We all badly need good software.
Blazin' Forth has been very carefully tested by a group of several people, some old Forthers, and some new ones. I believe this system is free of bugs, but suggestions for improvement are welcome, as are bug reports, should any new ones be discovered. A version for the C128 is planned which will include more features, such as Multi-tasking, a hashed dictionary structure (for super fast compiles) and other stuff. Dynamic vocabulary chaining is also being examined. Comments on any of these topics, or any other suggestions for improvements are very welcome. If you do communicate with me, please include the version number of your Forth system, (obtainable by typing .VERSION). I may be reached through Electronic mail:
Compuserve: 70066,603
Sourcemail: BDE712
Enjoy - and may the Forth be with you!
SDB
System Configuration, SAVE-FORTH
Forth differs from other languages in many ways - one of the nicer ones is that it gives you a choice of the final configuration of your own system. When you first run Blazin' Forth, everything will be present in the dictionary - the string extensions, the Turtle Graphics words, the Sound Words, all utilities, everything. Since source code is provided for all system extensions starting with THRU , you may FORGET up to that point, and selectively compile the words you need. It is even possible to have many different Forth versions available. You may choose to compile only the editor, and the sound extensions, for example, to give more room for music applications. You may then save the new system by using the word SAVE-FORTH . You will be prompted for a filename, and the new system will then be saved to disk. Note that the modules are relatively independent (the sound extensions, string extensions, and graphics extensions are completely independent), but all require that the assembler be loaded, and may also use a few, but by no means all, of the Utility words.
If you FORGET THRU , you will have 41167 bytes of available memory, which you can use in any way you wish. (Warning: You will also remove the Assembler, and the Editor from memory if you do this!) This is a *lot* of memory, since Forth code is extremely compact.
Note that this also gives you the freedom to define your own system extensions - if you want more or different utilities, you can add them. If you don't like the way the string functions work, you can change them. There is no need to work around a system word that doesn't do exactly what you want - you can customize this Forth to your liking. ( Warning: Do *not* save a new Forth system to a disk which contains Forth source screens. See the EDITOR section for more info.)
CONFIGURE
Using CONFIGURE, you may alter the actual memory configuration of the system. At power up, Blazin' Forth has 4 virtual disk buffers, located from $C000 to $D000 . Should you want more or less ( adding buffers subtracts from the dictionary space, and cuts down on disk accesses, removing buffers increases dictionary space) you can do this as by using CONFIGURE .
Example: Configure to use 1 disk buffer:
1 IS #BUF ( tell Forth how many buffers)
CONFIGURE ( reconfigure)
You can also lower the top of memory. This could be useful to reserve memory for an RS-232 buffer, sprite data, or machine language programs.
Example: Lower top of memory to $C000
HEX ( use Hexidecimal base)
$C000 IS LIMIT ( tell Forth how high it can go)
CONFIGURE ( reconfigure the system)
STARTUP
You can have FORTH come up running a resident application. STARTUP is a system variable that holds the code field address of the first word to execute when first run, on an error, or on a RESTART. Your word must take over the functions of the FORTH word QUIT . For example, to have FORTH run a word processing application when first run, we define a word FOO , that will execute this program:
: FOO BLK OFF SP! BEGIN RP! ( take on functions of QUIT)
PROCESS-WORDS ( execute the program ) AGAIN ; ( forever)
Now that this is done, we change STARTUP :
' FOO STARTUP ! ( store code-field of FOO in STARTUP )
And then save this as a new system file. Warning: Be careful not to cause an error at this point, or the system will dump you into your word processing program!
MISC:
This Forth ignores case, unless you are entering literal strings between quotes. So, for example, whether you type EMIT emit Emit or EmIt , the result will be the same - EMIT will be executed. This allows you to program in a mixture of upper and lower case.
Hitting RUN/STOP RESTORE will cause the FORTH system to warmstart. Default screen colors will be restored, the stack will be cleared, and decimal will become the current numeric base. Channels to the disk are unaffected, as are user programs and source screens in memory.
Typing RESTART will cause a cold start of the Forth system. This will return the system to the same configuration it had when first powered up.
Typing BYE will exit FORTH, and return to BASIC.
THRU is the best way to compile a sequential range of screens. It is far better than filling a screen with a series of LOAD commands. Example: 5 25 THRU will load screens from 5 to 25 inclusive.
*cn1;EDITOR*cn0
The EDITOR included with the system is the same as the one included in the book STARTING FORTH. All the editor commands described there are included in Blazin' Forth.
VERY IMPORTANT !!
Before accessing the disk drive, you must first type MOUNT, to initialize Forth's virtual memory system, and the disk drive. (Make sure a disk is in the drive before using this command.) This command must be used before LIST , INDEX , TRIAD , LOAD or THRU . MOUNT should also be used after changing disks. You only need to execute MOUNT once, at the start of an editing session, or before compiling (unless you RESTART , or change disks), but you can't get to the disk without it.
Forth uses random access files. Random access files don't show up in the directory. A disk can be filled with Forth screens and a directory listing will still show an empty disk. Therefore, it is very important not to mix Forth source screens with standard CBM files. (Note: You can use standard CBM file types from forth - you just shouldn't mix them with your source code!)
The disk drive light will remain lit while the system is enabled. This is normal, and should not cause you any concern.
The word DCLOSE will close all of the channels to the disk drive, and turn off the light on the drive.
*cn1;PROGRAM DOCUMENTATION*cn0
The following words are included to aid in program documentation:
xx LIST Lists screen# XX to the current output device. Enters the Editor.
xx TRIAD Lists the three screens including XX as a member to the current output device. The screens are formatted to fit on one normal sized sheet of printer paper. Example: 7 TRIAD will list screens 6, 7, and 8 to the screen. Includes PAUSE.
XX YY TRIADS list all triads from XX to YY . Note that this word assumes your printer has automatic paging. Includes PAUSE.
XX YY INDEX Lists all first lines of all the screens starting with XX through and including YY. If you follow the FORTH editing convention of starting each screen with a comment, you can use this word to quickly locate words. Includes pause.
WORDS Lists all the words in the current search order. Note that WORDS includes PAUSE. See PAUSE for more information.Same as the older VLIST.
*cn1;PROGRAM DEVELOPMENT AIDS*cn0
LOCATE
Forth Screens are great, allowing you to break up your programs into small modules, and even form interchangable libraries. One drawback, particularly in debugging, is the need to remember what screen number a particular word is located on. LOCATE removes this problem. For example, if you have a word, FOOBAR, which is in an application which you are currently testing, all you have to do is type LOCATE FOOBAR - and the system will list the screen which includes FOOBAR on the screen, and enter the editor. LOCATE will even access the disk if necessary! This is an extremely handy word. Try it, you'll soon wonder how you got along without it. Note that words in the pre-compiled portion cannot be LOCATEd.
DEBUGGING
Blazin' Forth contains several aids to assist in debugging and developing programs. Perhaps the most powerful word is TRACE. TRACE allows you to single-step through a Forth word, and observe it's execution step by step. For example, to trace a word called XYZZY , all you have to do is type TRACE XYZZY . Nothing will appear to happen, but the next time XYZZY is executed, Forth will enter single step mode. The word about to be executed will be displayed, along with the current stack contents. You have two options here. You can hit the RUN/STOP key, which will halt the program, and turn off the trace, or you can type CONTROL-P, which will enter PAUSE mode. Forth will display a P? prompt, and wait for you to do something. At this point, you can do anything you want. Alter the stack contents, LIST a screen, define a new word. You can also decide to trace a new word. This can be useful in tracing through levels of execution. To continue where you left off, type CONT . When the word has finished executing, normal program execution will resume. Once tracing has been enabled, there are only two ways to turn it off. Hitting the run/stop key during a trace, as described above. Or typing NOTRACE, either during a pause, or after the program has executed. Note: If you cause an error while in PAUSE mode, you will be dumped out of the current trace, but the trace is still enabled.
WATCH
Another kind of debugging aid, very useful in some situations, is WATCH. WATCH will keep an eye on a memory location, and halt program execution when it changes, printing out all the words executed in that line of execution. This can be handy when trying to locate a word that is altering the value of a variable, or even destroying the dictionary! For example, if you have a variable PROBLEM.VAR , which is getting changed to a bad value at some point, and you can't find out where, first initialize the variable to the value you want it too have, and then type: PROBLEM.VAR WATCH . When the value of PROBLEM.VAR changes from what it was when you executed WATCH, the system will stop program execution, and execute UNRAVEL , which displays the higher level nesting of Forth words which occurred up to that point.
UNRAVEL
Essentially, UNRAVEL displays all words executed by Forth up to the point that UNRAVEL was executed. It does this by decoding the contents of the return stack. (For more information on this, see Starting Forth.) This allows you to see what words preceeded a given words execution. For example:
: FOO BAR ;
: BAR FOO2 ;
: FOO2 FOO3 ;
: FOO3 UNRAVEL ;
When FOO is executed, it will ultimately arrive at FOO3 , which will execute UNRAVEL. This will cause the following display at your terminal:
FOO FOO3 FOO2 BAR 7106 INTERPRET RUN
(the words 7106 etc, are system words which are responsible for executing your input. They will always appear, and can just be ignored.)
This can be handy in determining what words lie in a certain execution path. Note that if you store values on the return stack, or if you use a DO LOOP, the return stack will contain stuff that is not relevant. UNRAVEL will just print these out as numbers, but this in itself, can be a very useful clue to debugging an application.
?PARAMS
This word will give an UNRAVEL trace if there are not enough parameters on the return stack. One use of ?PARAMS is to add run time error checking to the system. No run time error checking is performed by Forth. This allows applications to run faster, but can make life harder when you are developing an application. Forth does allow you to add this, if you want. When the program is finished, you can remove it, and the application will then run at full speed. For example, you can redefine the following:
: DROP 1 ?PARAMS DROP ;
: 2DROP 2 ?PARAMS 2DROP ;
etc.
DROP and 2DROP will now check the stack for the proper number of arguments, and give an error message, and an UNRAVEL dump if there are not enough arguments. One very nice thing about this way of doing things is that you don't have to re-edit your application once it's finished. You can redefine all of FORTH's stack operators in this way, load them in, and then load your application. When it's debugged, simply loading your application without loading the redefined stack operators will remove the run-time error checking, and allow your application to run at full speed.
This is only one example - such runtime error checks can be very useful, and are limited only by your imagination and debugging skills.
.S
.S is a common and highly useful word. It non-destructively prints out the contents of the stack, or the message STACK EMPTY, if there is nothing on the stack. Note that this version of .S displays unsigned numbers, so, for example, a value of -1 will display as 65535.
DUMP
DUMP takes two arguments, a starting address, and a count. It will then dump the contents of the memory locations to the current output device (in hex) and also the symbolic ASCII contents of those addresses. A period will be displayed if there is no corresponding ASCII character. This can be extremely useful for monitoring memory arrays, or simply trying too figure out why a CODE defintion doesn't work. Note that DUMP includes PAUSE. See PAUSE for more information.
EXAMPLE:
2000 64 DUMP will display 64 memory locations starting with 2000.
DEFER and IS
These two words form a remarkably useful combination. DEFER is similar to the FORWARD declarations of other compilers. Ordinarily, you must compile a word before using it in another definition. DEFER lets you out of this obligation. EXAMPLE:
DEFER FOO ( postpone working on FOO)
: BAR FOO ;
Later in the application, you may define:
: (FOO) ." This is foo. " ;
At this point, FOO will simply give an error message, "UNSPECIFIED VECTOR". You must tell FOO what to do, like this:
' (FOO) IS FOO // make FOO do (FOO)
Note the tick (') - it's important! Now, typing FOO will result in the execution of (FOO).
Note that if you dislike the way a DEFERed word is performing, you can redefine it without recompiling the entire application. For example:
: NEWFOO ." This is new foo." ;
' NEWFOO IS FOO
FOO will now execute NEWFOO, instead of (FOO). This allows you the incredible freedom of altering an already compiled word's behaviour - this is, so far as I know, unique to Forth!
Note that the usefulness of DEFER IS isn't limited to development. IS may be used inside a definition, and it's a convenient way to handle vectored execution. (See Starting Forth for more on vectored execution.) For example:
DEFER MESSAGE
: HI ." Hi there." ;
: BYE ." See you later " ;
: SOLONG ['] BYE IS MESSAGE ;
: HELLO ['] HI IS MESSAGE ;
Executing SOLONG will cause MESSAGE to print "See you later" while executing HELLO will cause MESSAGE to print "Hi there". Note that when used inside a colon definition, you need to use ['] instead of ' .
